Captures the brainstorming session outcome for the three-release plan:

- v2.1 "Reliability + Zero-Friction Install" — close the bleeding,
  merge contributor PRs (#6, #13), fix #11, ship engram update /
  engram doctor / engram setup, close #14 via Bash PostTool parser.
- v2.2 "Spine" — integrate Serena as an engram provider via a new
  reusable MCP-client subsystem. Engram becomes the orchestrator,
  not a fighter of semantic-search tools.
- v3.0 "Landmines" — mistakes-as-moat expansion + R2 repositioning
  ("the context tool that remembers what broke"). Keep the name,
  rebrand the tagline.

Strategic choices recorded:
- Trilogy (alpha) over mega-release (beta) or split (gamma)
- R2 (keep name, rebrand tagline) over R1 (keep everything) or R3
  (rename, prohibitive cost)
- Update UX: option A — passive notify + manual install, zero
  telemetry, ENGRAM_NO_UPDATE_CHECK + \$CI opt-out

Grounded in measured research:
- npm downloads 1.3K/week, 10/day organic baseline
- r/LocalLLaMA post ratioed (0.44) due to name collision with 4
  other "Engram" projects launched Mar-Apr 2026
- Serena just hit stable with published evals — credible complement
- 2 active external contributors writing substantive PRs

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Adds a strict parser for file-mutating Bash commands — rm, mv, cp,
git rm, git mv, and single-redirect commands. Returns a list of
FileOp { action: "reindex" | "prune", path: absolute } that the
PostToolUse dispatch path will hand to syncFile() from watcher.ts.

This is HALF of issue #14. The other half is the dispatch wire-up
(route PostToolUse:Bash through this parser and invoke syncFile for
each op) which depends on PR #13's --auto-reindex flag landing first.
The parser ships standalone so it is review-ready and test-complete
before #13 merges.

Parser philosophy (mirrors handlers/bash.ts PreToolUse):

  STRICT. Any ambiguity → passthrough. False negatives cost tokens;
  false positives corrupt the graph. Optimize for the latter.

Supported shapes (intercepted):
  rm [-rf] <path> [<path>...]           → prune each
  mv <src> <dst>                        → prune src, reindex dst
  cp <src> <dst>                        → reindex dst
  git rm [-r] <path>                    → prune
  git mv <src> <dst>                    → prune src, reindex dst
  <simple-cmd> > <dst>                  → reindex dst (single redirect)
  <simple-cmd> >> <dst>                 → reindex dst (single redirect)

Intentionally NOT supported (pass through):
  - globs (rm *.ts)
  - pipes (find . | xargs rm)
  - subshells / command substitution (\$(…), backticks, <(…), >(…))
  - touch (empty file, nothing to index)
  - directory-level ops (needs directory-prefix prune primitive,
    tracked for v2.2)

Tests: 29 new tests across rm/mv/cp/git-rm/git-mv variants,
redirections, pass-through edge cases, and the high-level
handleBashPostTool wrapper.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…h-postool

## Closes #11 — AST/LSP reported unavailable despite enabled

Credit: Tommaso Tessarolo (@ttessarolo) — precise forensics + suggested fix.

### checkAst: flattened-bundle path resolution

When tsup/esbuild flattens the CLI into `engramx/dist/chunk-*.js`,
import.meta.url resolves `here = engramx/dist`. The previous candidates:

  - `here + '../grammars'`          → engramx/grammars  (✗ does not exist)
  - `here + '../../dist/grammars'`  → parent/dist/grammars (✗ does not exist)

Fix: add `join(here, "grammars")` as the FIRST candidate. This resolves
to `engramx/dist/grammars/` where grammars actually ship. Dev-time
layout (src/intercept/) still works via the third candidate.

### checkLsp: socket candidates out of sync

The check only looked for `tsserver.sock` and `typescript-language-server.sock`,
but `lsp-connection.ts::candidateSockets()` also probes:

  - tsserver-<uid>.sock
  - lsp-server.sock
  - pyright-<uid>.sock
  - rust-analyzer.sock

Also: the `.engram/lsp-available` flag was documented as "written by
the lsp provider on successful connection" but no code path writes it.
Kept the marker as an explicit user opt-in (back-compat) but synced
the socket list with lsp-connection.ts so HUD availability matches
actual provider availability.

### Regression test

tests/intercept/component-status-11.test.ts — asserts refreshComponentStatus
returns a boolean for every scenario + honors the .engram/lsp-available
marker.

## Wires bash-postool into PostToolUse (issue #14 full wire-up)

With @gabiudrescu's PR #12 already merged, syncFile() is available.
We can wire the v2.1 Bash parser into the PostToolUse observer path
without waiting for PR #13's install-hook --auto-reindex flag.

- post-tool.ts imports handleBashPostTool + syncFile.
- On PostToolUse with tool=Bash, parse the command; for each FileOp,
  call syncFile(absPath, projectRoot) fire-and-forget.
- Gated by ENGRAM_AUTO_REINDEX=1 (opt-in) until PR #13 lands and we
  can migrate to the install-hook flag.
- Observer semantics preserved: never blocks the PostToolUse response,
  errors swallowed, never surfaces bugs to Claude Code.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Follow-up to cherry-picks b4f7944 (PR #6 commit 1) + 411ad13 (PR #6 commit 2)
from @mechtar-ru.

Deletes redundant DEFAULT_EXCLUDED_DIRS (15 entries) + loadEngramIgnore()
(16 lines) that lived in parallel with the canonical DEFAULT_SKIP_DIRS +
loadIgnorePatterns() pair (the latter shipped in v2.1.0 via PR #13).
Both pairs implemented the same .engramignore feature — keeping only
the v2.1 canonical pair keeps one source of truth.

Also tightens entries typing: 'let entries: Dirent[]' in extractDirectory
(ReturnType<typeof readdirSync> resolves to the string[] default overload,
not the Dirent[] shape actually returned with { withFileTypes: true }).

All 784 tests pass. TypeScript clean.

Closes issue #5 (via PR #6 content: MAX_DEPTH=100 + MAX_FILES_PER_COMMIT=50
+ .engramignore support + expanded default skip dirs — the OOM crash on
init for 2.2GB/34K-file projects like Axolotl is fixed).

First release in the v2.1 / v2.2 / v3.0 elevation trilogy. Ships:

- engram update / doctor / setup — zero-friction install + self-upgrade
- engram init --with-hook — one-command init + hook install
- First-run hint on stderr (throttled, \$CI-safe, opt-out env)
- Bash PostTool parser for auto-reindex (issue NickCirv#14 half, opt-in via
  ENGRAM_AUTO_REINDEX=1 until PR NickCirv#13's --auto-reindex flag becomes
  authoritative)
- Fix issue NickCirv#11 — AST grammar detection in flattened bundles
  (@ttessarolo) + LSP socket candidate sync
- ESM require() runtime bug fix across doctor/setup (would have
  silently failed in production; caught by in-process audit, not by
  CI because vitest provides CommonJS interop)
- Windows cross-platform test fix for bash-postool (platform-native
  path.resolve in expected values, not hard-coded POSIX)

See CHANGELOG.md [2.1.0] for full detail + contributor credits.

Release artifacts:
- package.json version 2.0.2 → 2.1.0
- package-lock.json synced
- CHANGELOG [Unreleased] entries rehomed under [2.1.0] — 2026-04-21

Post-merge steps (not in this commit):
  git tag -a v2.1.0 -m "v2.1.0 Reliability + Zero-Friction Install"
  git push --tags
  npm publish
  gh release create v2.1.0 --generate-notes

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>